---
title: migrate from-package-json
sidebar_label: from-package-json
---

Use the `moon migrate from-package-json <project>` sub-command to migrate a project's `package.json`
to our [`moon.yml`](../../config/project) format. When ran, the following changes are made:

- Converts `package.json` scripts to `moon.yml` [tasks](../../config/project#tasks). Scripts and
  tasks are not 1:1, so we'll convert as close as possible while retaining functionality.
- Updates `package.json` by removing all converted scripts. If all scripts were converted, the
  entire block is removed.
- Links `package.json` dependencies as `moon.yml` [dependencies](../../config/project#dependson)
  (`dependsOn`). Will map a package's name to their moon project name.

This command is ran _per project_, and for this to operate correctly, requires all
[projects to be configured in the workspace](../../config/workspace#projects). There's also a
handful of [requirements and caveats](#caveats) to be aware of!

```shell
$ moon --log debug migrate from-package-json app
```

:::caution

moon does its best to infer the [`local`](../../config/project#local) option, given the small amount
of information available to use. When this option is incorrectly set, it'll result in CI
environments hanging for tasks that are long-running or never-ending (development servers, etc), or
won't run builds that should be. Be sure to audit each task after migration!

:::

### Arguments

- `<project>` - Name of a project, as defined in [`projects`](../../config/workspace#projects).

## Caveats

- When running a script within another script, the full invocation of `npm run ...`, `pnpm run ...`,
  or `yarn run ...` must be used. Shorthand variants are **not** supported, for example, `npm test`
  or `yarn lint` or `pnpm format`. We cannot guarantee that moon will parse these correctly
  otherwise.

  ```diff title="package.json"
  {
  	// ...
  	"scripts": {
  		"lint": "eslint .",
  -		"lint:fix": "yarn lint --fix",
  +		"lint:fix": "yarn run lint --fix",
  	}
  }
  ```

- Scripts that run multiple commands with the AND operator (`&&`) will create an individual
  transient task for each command, with all tasks linked _in-order_ using task
  [`deps`](../../config/project#deps). These commands _will not_ run in parallel. For example, given
  the following script:

  ```json title="package.json"
  {
    // ...
    "scripts": {
      // ...
      "check": "yarn run lint && yarn run test && yarn run typecheck"
    }
  }
  ```

  Would create 3 tasks that create the dependency chain:
  `check-dep1 (lint) -> check-dep2 (test) -> check (typecheck)`, instead of the expected parallel
  execution of `lint | test | typecheck -> check`. If you would prefer these commands to run in
  parallel, then you'll need to craft your tasks manually.

- Scripts that change directory (`cd ...`), use pipes (`|`), redirects (`>`), or the OR operator
  (`||`) are **not** supported and will be skipped. Tasks and scripts are not 1:1 in functionality,
  as tasks represent that state of a single command execution. However, you can wrap this
  functionality in a
  [custom script that executes it on the task's behalf](../../faq#how-to-pipe-or-redirect-tasks).

- [Life cycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts) are
  **not** converted to tasks and will remain in `package.json` since they're required by npm (and
  other package managers). However, their commands _will_ be updated to execute moon commands when
  applicable.

  ```diff title="package.json"
  {
  	// ...
  	"scripts": {
  -		"preversion": "yarn run lint && yarn run test",
  +		"preversion": "moon run project:lint && moon run project:test",
  	}
  }
  ```

  > This _does not_ apply to `run`, `start`, `stop`, and `test` life cycles.

- "Post" life cycles for
  [user defined scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#npm-run-user-defined) do
  not work, as moon tasks have no concept of "run this after the task completes", so we suggest
  _against using these entirely_. However, we still convert the script and include the base script
  as a task dependency.

  For example, a `posttest` script would be converted into a `posttest` task, with the `test` task
  included in [`deps`](../../config/project#deps). For this to actually run correctly, you'll need
  to use `moon run <project>:posttest` AND NOT `moon run <project>:test`.
